home *** CD-ROM | disk | FTP | other *** search
/ Chip 2007 January, February, March & April / Chip-Cover-CD-2007-02.iso / Pakiet bezpieczenstwa / mini Pentoo LiveCD 2006.1 / mpentoo-2006.1.iso / livecd.squashfs / usr / include / gaim / conversation.h < prev    next >
Encoding:
C/C++ Source or Header  |  2005-10-18  |  40.7 KB  |  1,514 lines
  1. /**
  2.  * @file conversation.h Conversation API
  3.  * @ingroup core
  4.  *
  5.  * gaim
  6.  *
  7.  * Gaim is the legal property of its developers, whose names are too numerous
  8.  * to list here.  Please refer to the COPYRIGHT file distributed with this
  9.  * source distribution.
  10.  *
  11.  * This program is free software; you can redistribute it and/or modify
  12.  * it under the terms of the GNU General Public License as published by
  13.  * the Free Software Foundation; either version 2 of the License, or
  14.  * (at your option) any later version.
  15.  *
  16.  * This program is distributed in the hope that it will be useful,
  17.  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  18.  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19.  * GNU General Public License for more details.
  20.  *
  21.  * You should have received a copy of the GNU General Public License
  22.  * along with this program; if not, write to the Free Software
  23.  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  24.  *
  25.  * @see @ref conversation-signals
  26.  */
  27. #ifndef _GAIM_CONVERSATION_H_
  28. #define _GAIM_CONVERSATION_H_
  29.  
  30. /**************************************************************************/
  31. /** Data Structures                                                       */
  32. /**************************************************************************/
  33.  
  34. typedef struct _GaimConvWindowUiOps   GaimConvWindowUiOps;
  35. typedef struct _GaimConvWindow        GaimConvWindow;
  36. typedef struct _GaimConversationUiOps GaimConversationUiOps;
  37. typedef struct _GaimConversation      GaimConversation;
  38. typedef struct _GaimConvIm            GaimConvIm;
  39. typedef struct _GaimConvChat          GaimConvChat;
  40. typedef struct _GaimConvChatBuddy     GaimConvChatBuddy;
  41.  
  42. /**
  43.  * A type of conversation.
  44.  */
  45. typedef enum
  46. {
  47.     GAIM_CONV_UNKNOWN = 0, /**< Unknown conversation type. */
  48.     GAIM_CONV_IM,          /**< Instant Message.           */
  49.     GAIM_CONV_CHAT,        /**< Chat room.                 */
  50.     GAIM_CONV_MISC         /**< A misc. conversation.      */
  51.  
  52. } GaimConversationType;
  53.  
  54. /**
  55.  * Unseen text states.
  56.  */
  57. typedef enum
  58. {
  59.     GAIM_UNSEEN_NONE = 0,  /**< No unseen text in the conversation. */
  60.     GAIM_UNSEEN_TEXT,      /**< Unseen text in the conversation.    */
  61.     GAIM_UNSEEN_NICK,      /**< Unseen text and the nick was said.  */
  62.     GAIM_UNSEEN_EVENT      /**< Unseen events in the conversation.  */
  63.  
  64. } GaimUnseenState;
  65.  
  66. /**
  67.  * Conversation update type.
  68.  */
  69. typedef enum
  70. {
  71.     GAIM_CONV_UPDATE_ADD = 0, /**< The buddy associated with the conversation
  72.                                    was added.   */
  73.     GAIM_CONV_UPDATE_REMOVE,  /**< The buddy associated with the conversation
  74.                                    was removed. */
  75.     GAIM_CONV_UPDATE_ACCOUNT, /**< The gaim_account was changed. */
  76.     GAIM_CONV_UPDATE_TYPING,  /**< The typing state was updated. */
  77.     GAIM_CONV_UPDATE_UNSEEN,  /**< The unseen state was updated. */
  78.     GAIM_CONV_UPDATE_LOGGING, /**< Logging for this conversation was
  79.                                    enabled or disabled. */
  80.     GAIM_CONV_UPDATE_TOPIC,   /**< The topic for a chat was updated. */
  81.     /*
  82.      * XXX These need to go when we implement a more generic core/UI event
  83.      * system.
  84.      */
  85.     GAIM_CONV_ACCOUNT_ONLINE,  /**< One of the user's accounts went online.  */
  86.     GAIM_CONV_ACCOUNT_OFFLINE, /**< One of the user's accounts went offline. */
  87.     GAIM_CONV_UPDATE_AWAY,     /**< The other user went away.                */
  88.     GAIM_CONV_UPDATE_ICON,     /**< The other user's buddy icon changed.     */
  89.     GAIM_CONV_UPDATE_TITLE,
  90.     GAIM_CONV_UPDATE_CHATLEFT,
  91.  
  92.     GAIM_CONV_UPDATE_FEATURES, /**< The features for a chat have changed */
  93.  
  94. } GaimConvUpdateType;
  95.  
  96. /**
  97.  * The typing state of a user.
  98.  */
  99. typedef enum
  100. {
  101.     GAIM_NOT_TYPING = 0,  /**< Not typing.                 */
  102.     GAIM_TYPING,          /**< Currently typing.           */
  103.     GAIM_TYPED            /**< Stopped typing momentarily. */
  104.  
  105. } GaimTypingState;
  106.  
  107. /**
  108.  * Flags applicable to a message. Most will have send, recv or system.
  109.  */
  110. typedef enum
  111. {
  112.     GAIM_MESSAGE_SEND      = 0x0001, /**< Outgoing message.        */
  113.     GAIM_MESSAGE_RECV      = 0x0002, /**< Incoming message.        */
  114.     GAIM_MESSAGE_SYSTEM    = 0x0004, /**< System message.          */
  115.     GAIM_MESSAGE_AUTO_RESP = 0x0008, /**< Auto response.           */
  116.     GAIM_MESSAGE_COLORIZE  = 0x0010, /**< Colorize nicks.          */
  117.     GAIM_MESSAGE_NICK      = 0x0020, /**< Contains your nick.      */
  118.     GAIM_MESSAGE_NO_LOG    = 0x0040, /**< Do not log.              */
  119.     GAIM_MESSAGE_WHISPER   = 0x0080, /**< Whispered message.       */
  120.     GAIM_MESSAGE_ERROR     = 0x0200, /**< Error message.           */
  121.     GAIM_MESSAGE_DELAYED   = 0x0400  /**< Delayed message.         */
  122. } GaimMessageFlags;
  123.  
  124. /**
  125.  * Flags applicable to users in Chats.
  126.  */
  127. typedef enum
  128. {
  129.     GAIM_CBFLAGS_NONE          = 0x0000, /**< No flags                     */
  130.     GAIM_CBFLAGS_VOICE         = 0x0001, /**< Voiced user or "Participant" */
  131.     GAIM_CBFLAGS_HALFOP        = 0x0002, /**< Half-op                      */
  132.     GAIM_CBFLAGS_OP            = 0x0004, /**< Channel Op or Moderator      */
  133.     GAIM_CBFLAGS_FOUNDER       = 0x0008  /**< Channel Founder              */
  134. } GaimConvChatBuddyFlags;
  135.  
  136. #include "account.h"
  137. #include "buddyicon.h"
  138. #include "log.h"
  139. #include "server.h"
  140.  
  141. /**
  142.  * Conversation window operations.
  143.  *
  144.  * Any UI representing a window must assign a filled-out gaim_conv_window_ops
  145.  * structure to the GaimConvWindow.
  146.  */
  147. struct _GaimConvWindowUiOps
  148. {
  149.     GaimConversationUiOps *(*get_conversation_ui_ops)(void);
  150.  
  151.     void (*new_window)(GaimConvWindow *win);
  152.     void (*destroy_window)(GaimConvWindow *win);
  153.  
  154.     void (*show)(GaimConvWindow *win);
  155.     void (*hide)(GaimConvWindow *win);
  156.     void (*raise)(GaimConvWindow *win);
  157.     void (*flash)(GaimConvWindow *win);
  158.  
  159.     void (*switch_conversation)(GaimConvWindow *win, unsigned int index);
  160.     void (*add_conversation)(GaimConvWindow *win, GaimConversation *conv);
  161.     void (*remove_conversation)(GaimConvWindow *win, GaimConversation *conv);
  162.     void (*move_conversation)(GaimConvWindow *win, GaimConversation *conv,
  163.                               unsigned int newIndex);
  164.  
  165.     int (*get_active_index)(const GaimConvWindow *win);
  166.     gboolean (*has_focus)(GaimConvWindow *win);
  167. };
  168.  
  169. /**
  170.  * Conversation operations and events.
  171.  *
  172.  * Any UI representing a conversation must assign a filled-out
  173.  * GaimConversationUiOps structure to the GaimConversation.
  174.  */
  175. struct _GaimConversationUiOps
  176. {
  177.     void (*destroy_conversation)(GaimConversation *conv);
  178.     void (*write_chat)(GaimConversation *conv, const char *who,
  179.                        const char *message, GaimMessageFlags flags,
  180.                        time_t mtime);
  181.     void (*write_im)(GaimConversation *conv, const char *who,
  182.                      const char *message, GaimMessageFlags flags,
  183.                      time_t mtime);
  184.     void (*write_conv)(GaimConversation *conv, const char *who,
  185.                        const char *message, GaimMessageFlags flags,
  186.                        time_t mtime);
  187.  
  188.     void (*chat_add_user)(GaimConversation *conv, const char *user, gboolean new_arrival);
  189.     void (*chat_add_users)(GaimConversation *conv, GList *users);
  190.     void (*chat_rename_user)(GaimConversation *conv,
  191.                              const char *old_name, const char *new_name);
  192.     void (*chat_remove_user)(GaimConversation *conv, const char *user);
  193.     void (*chat_remove_users)(GaimConversation *conv, GList *users);
  194.     void (*chat_update_user)(GaimConversation *conv, const char *user);
  195.  
  196.     void (*update_progress)(GaimConversation *conv, float percent);
  197.  
  198.     gboolean (*has_focus)(GaimConversation *conv);
  199.  
  200.     /* Events */
  201.     void (*updated)(GaimConversation *conv, GaimConvUpdateType type);
  202.  
  203. };
  204.  
  205. /**
  206.  * A core representation of a graphical window containing one or more
  207.  * conversations.
  208.  */
  209. struct _GaimConvWindow
  210. {
  211.     GList *conversations;              /**< The conversations in the window. */
  212.     size_t conversation_count;         /**< The number of conversations.     */
  213.  
  214.     GaimConvWindowUiOps *ui_ops;       /**< UI-specific window operations.   */
  215.     void *ui_data;                     /**< UI-specific data.                */
  216. };
  217.  
  218. /**
  219.  * Data specific to Instant Messages.
  220.  */
  221. struct _GaimConvIm
  222. {
  223.     GaimConversation *conv;            /**< The parent conversation.     */
  224.  
  225.     GaimTypingState typing_state;      /**< The current typing state.    */
  226.     guint  typing_timeout;             /**< The typing timer handle.     */
  227.     time_t type_again;                 /**< The type again time.         */
  228.     guint  type_again_timeout;         /**< The type again timer handle. */
  229.  
  230.     GaimBuddyIcon *icon;               /**< The buddy icon.              */
  231. };
  232.  
  233. /**
  234.  * Data specific to Chats.
  235.  */
  236. struct _GaimConvChat
  237. {
  238.     GaimConversation *conv;          /**< The parent conversation.      */
  239.  
  240.     GList *in_room;                  /**< The users in the room.        */
  241.     GList *ignored;                  /**< Ignored users.                */
  242.     char  *who;                      /**< The person who set the topic. */
  243.     char  *topic;                    /**< The topic.                    */
  244.     int    id;                       /**< The chat ID.                  */
  245.     char *nick;                      /**< Your nick in this chat.       */
  246.  
  247.     gboolean left;                   /**< We left the chat and kept the window open */
  248. };
  249.  
  250. /**
  251.  * Data for "Chat Buddies"
  252.  */
  253. struct _GaimConvChatBuddy
  254. {
  255.     char *name;                      /**< The name                      */
  256.     GaimConvChatBuddyFlags flags;    /**< Flags (ops, voice etc.)       */
  257. };
  258.  
  259. /**
  260.  * A core representation of a conversation between two or more people.
  261.  *
  262.  * The conversation can be an IM or a chat. Each conversation is kept
  263.  * in a GaimConvWindow and has a UI representation.
  264.  */
  265. struct _GaimConversation
  266. {
  267.     GaimConversationType type;  /**< The type of conversation.          */
  268.  
  269.     GaimAccount *account;       /**< The user using this conversation.  */
  270.     GaimConvWindow *window;     /**< The parent window.                 */
  271.  
  272.     int conversation_pos;       /**< The position in the window's list. */
  273.  
  274.     char *name;                 /**< The name of the conversation.      */
  275.     char *title;                /**< The window title.                  */
  276.  
  277.     gboolean logging;           /**< The status of logging.             */
  278.  
  279.     GaimLog *log;               /**< This conversation's log            */
  280.  
  281.     GList *send_history;        /**< The send history.                  */
  282.     GString *history;           /**< The conversation history.          */
  283.  
  284.     GaimUnseenState unseen;     /**< The unseen tab state.              */
  285.  
  286.     union
  287.     {
  288.         GaimConvIm   *im;       /**< IM-specific data.                  */
  289.         GaimConvChat *chat;     /**< Chat-specific data.                */
  290.         void *misc;             /**< Misc. data.                        */
  291.  
  292.     } u;
  293.  
  294.     GaimConversationUiOps *ui_ops;           /**< UI-specific operations. */
  295.     void *ui_data;                           /**< UI-specific data.       */
  296.  
  297.     GHashTable *data;                        /**< Plugin-specific data.   */
  298.   
  299.     GaimConnectionFlags features; /**< The supported features */
  300.  
  301. };
  302.  
  303. typedef void (*GaimConvPlacementFunc)(GaimConversation *);
  304.  
  305. #ifdef __cplusplus
  306. extern "C" {
  307. #endif
  308.  
  309. /**************************************************************************/
  310. /** @name Conversation Window API                                         */
  311. /**************************************************************************/
  312. /*@{*/
  313.  
  314. /**
  315.  * Creates a new conversation window.
  316.  *
  317.  * This window is added to the list of windows, but is not shown until
  318.  * gaim_conv_window_show() is called.
  319.  *
  320.  * @return The new conversation window.
  321.  */
  322. GaimConvWindow *gaim_conv_window_new(void);
  323.  
  324. /**
  325.  * Destroys the specified conversation window and all conversations in it.
  326.  *
  327.  * @param win The window to destroy.
  328.  */
  329. void gaim_conv_window_destroy(GaimConvWindow *win);
  330.  
  331. /**
  332.  * Shows the specified conversation window.
  333.  *
  334.  * @param win The window.
  335.  */
  336. void gaim_conv_window_show(GaimConvWindow *win);
  337.  
  338. /**
  339.  * Hides the specified conversation window.
  340.  *
  341.  * @param win The window.
  342.  */
  343. void gaim_conv_window_hide(GaimConvWindow *win);
  344.  
  345. /**
  346.  * Raises the specified conversation window.
  347.  *
  348.  * @param win The window.
  349.  */
  350. void gaim_conv_window_raise(GaimConvWindow *win);
  351.  
  352. /**
  353.  * Causes the window to flash for IM notification, if the UI supports this.
  354.  *
  355.  * @param win The window.
  356.  */
  357. void gaim_conv_window_flash(GaimConvWindow *win);
  358.  
  359. /**
  360.  * Sets the specified window's UI window operations structure.
  361.  *
  362.  * @param win The window.
  363.  * @param ops The UI window operations structure.
  364.  */
  365. void gaim_conv_window_set_ui_ops(GaimConvWindow *win,
  366.                                  GaimConvWindowUiOps *ops);
  367.  
  368. /**
  369.  * Returns the specified window's UI window operations structure.
  370.  *
  371.  * @param win The window.
  372.  *
  373.  * @return The UI window operations structure.
  374.  */
  375. GaimConvWindowUiOps *gaim_conv_window_get_ui_ops(const GaimConvWindow *win);
  376.  
  377. /**
  378.  * Adds a conversation to this window.
  379.  *
  380.  * If the conversation already has a parent window, this will do nothing.
  381.  *
  382.  * @param win  The window.
  383.  * @param conv The conversation.
  384.  *
  385.  * @return The new index of the conversation in the window.
  386.  */
  387. int gaim_conv_window_add_conversation(GaimConvWindow *win,
  388.                                       GaimConversation *conv);
  389.  
  390. /**
  391.  * Removes the conversation at the specified index from the window.
  392.  *
  393.  * If there is no conversation at this index, this will do nothing.
  394.  *
  395.  * @param win   The window.
  396.  * @param index The index of the conversation.
  397.  *
  398.  * @return The conversation removed.
  399.  */
  400. GaimConversation *gaim_conv_window_remove_conversation(GaimConvWindow *win,
  401.                                                        unsigned int index);
  402.  
  403. /**
  404.  * Moves the conversation at the specified index in a window to a new index.
  405.  *
  406.  * @param win      The window.
  407.  * @param index     The index of the conversation to move.
  408.  * @param new_index The new index.
  409.  */
  410. void gaim_conv_window_move_conversation(GaimConvWindow *win,
  411.                                         unsigned int index,
  412.                                         unsigned int new_index);
  413.  
  414. /**
  415.  * Returns the conversation in the window at the specified index.
  416.  *
  417.  * If the index is out of range, this returns @c NULL.
  418.  *
  419.  * @param win   The window.
  420.  * @param index The index containing a conversation.
  421.  *
  422.  * @return The conversation at the specified index.
  423.  */
  424. GaimConversation *gaim_conv_window_get_conversation_at(
  425.         const GaimConvWindow *win, unsigned int index);
  426.  
  427. /**
  428.  * Returns the number of conversations in the window.
  429.  *
  430.  * @param win The window.
  431.  *
  432.  * @return The number of conversations.
  433.  */
  434. size_t gaim_conv_window_get_conversation_count(const GaimConvWindow *win);
  435.  
  436. /**
  437.  * Switches the active conversation to the one at the specified index.
  438.  *
  439.  * If @a index is out of range, this does nothing.
  440.  *
  441.  * @param win   The window.
  442.  * @param index The new index.
  443.  */
  444. void gaim_conv_window_switch_conversation(GaimConvWindow *win,
  445.                                           unsigned int index);
  446.  
  447. /**
  448.  * Returns the active conversation in the window.
  449.  *
  450.  * @param win The window.
  451.  *
  452.  * @return The active conversation.
  453.  */
  454. GaimConversation *gaim_conv_window_get_active_conversation(
  455.         const GaimConvWindow *win);
  456.  
  457. /**
  458.  * Determines if a conversation window has focus
  459.  *
  460.  * @param win The window.
  461.  *
  462.  * @return @c TRUE if the conversation window has focus, @c FALSE if
  463.  * it does not or the UI does not have a concept of window focus
  464.  */
  465. gboolean gaim_conv_window_has_focus(GaimConvWindow *win);
  466.  
  467. /**
  468.  * Returns the list of conversations in the specified window.
  469.  *
  470.  * @param win The window.
  471.  *
  472.  * @return The list of conversations.
  473.  */
  474. GList *gaim_conv_window_get_conversations(const GaimConvWindow *win);
  475.  
  476. /**
  477.  * Returns a list of all windows.
  478.  *
  479.  * @return A list of windows.
  480.  */
  481. GList *gaim_get_windows(void);
  482.  
  483. /**
  484.  * Returns the first window containing a conversation of the specified type.
  485.  *
  486.  * @param type The conversation type.
  487.  *
  488.  * @return The window if found, or @c NULL if not found.
  489.  */
  490. GaimConvWindow *gaim_get_first_window_with_type(GaimConversationType type);
  491. /**
  492.  * Returns the last window containing a conversation of the specified type.
  493.  *
  494.  * @param type The conversation type.
  495.  *
  496.  * @return The window if found, or @c NULL if not found.
  497.  */
  498. GaimConvWindow *gaim_get_last_window_with_type(GaimConversationType type);
  499.  
  500. /*@}*/
  501.  
  502. /**************************************************************************/
  503. /** @name Conversation API                                                */
  504. /**************************************************************************/
  505. /*@{*/
  506.  
  507. /**
  508.  * Creates a new conversation of the specified type.
  509.  *
  510.  * @param type    The type of conversation.
  511.  * @param account The account opening the conversation window on the gaim
  512.  *                user's end.
  513.  * @param name    The name of the conversation.
  514.  *
  515.  * @return The new conversation.
  516.  */
  517. GaimConversation *gaim_conversation_new(GaimConversationType type,
  518.                                         GaimAccount *account,
  519.                                         const char *name);
  520.  
  521. /**
  522.  * Destroys the specified conversation and removes it from the parent
  523.  * window.
  524.  *
  525.  * If this conversation is the only one contained in the parent window,
  526.  * that window is also destroyed.
  527.  *
  528.  * @param conv The conversation to destroy.
  529.  */
  530. void gaim_conversation_destroy(GaimConversation *conv);
  531.  
  532. /**
  533.  * Returns the specified conversation's type.
  534.  *
  535.  * @param conv The conversation.
  536.  *
  537.  * @return The conversation's type.
  538.  */
  539. GaimConversationType gaim_conversation_get_type(const GaimConversation *conv);
  540.  
  541. /**
  542.  * Sets the specified conversation's UI operations structure.
  543.  *
  544.  * @param conv The conversation.
  545.  * @param ops  The UI conversation operations structure.
  546.  */
  547. void gaim_conversation_set_ui_ops(GaimConversation *conv,
  548.                                   GaimConversationUiOps *ops);
  549.  
  550. /**
  551.  * Returns the specified conversation's UI operations structure.
  552.  *
  553.  * @param conv The conversation.
  554.  *
  555.  * @return The operations structure.
  556.  */
  557. GaimConversationUiOps *gaim_conversation_get_ui_ops(
  558.         const GaimConversation *conv);
  559.  
  560. /**
  561.  * Sets the specified conversation's gaim_account.
  562.  *
  563.  * This gaim_account represents the user using gaim, not the person the user
  564.  * is having a conversation/chat/flame with.
  565.  *
  566.  * @param conv The conversation.
  567.  * @param account The gaim_account.
  568.  */
  569. void gaim_conversation_set_account(GaimConversation *conv,
  570.                                    GaimAccount *account);
  571.  
  572. /**
  573.  * Returns the specified conversation's gaim_account.
  574.  *
  575.  * This gaim_account represents the user using gaim, not the person the user
  576.  * is having a conversation/chat/flame with.
  577.  *
  578.  * @param conv The conversation.
  579.  *
  580.  * @return The conversation's gaim_account.
  581.  */
  582. GaimAccount *gaim_conversation_get_account(const GaimConversation *conv);
  583.  
  584. /**
  585.  * Returns the specified conversation's gaim_connection.
  586.  *
  587.  * This is the same as gaim_conversation_get_user(conv)->gc.
  588.  *
  589.  * @param conv The conversation.
  590.  *
  591.  * @return The conversation's gaim_connection.
  592.  */
  593. GaimConnection *gaim_conversation_get_gc(const GaimConversation *conv);
  594.  
  595. /**
  596.  * Sets the specified conversation's title.
  597.  *
  598.  * @param conv  The conversation.
  599.  * @param title The title.
  600.  */
  601. void gaim_conversation_set_title(GaimConversation *conv, const char *title);
  602.  
  603. /**
  604.  * Returns the specified conversation's title.
  605.  *
  606.  * @param conv The conversation.
  607.  *
  608.  * @return The title.
  609.  */
  610. const char *gaim_conversation_get_title(const GaimConversation *conv);
  611.  
  612. /**
  613.  * Automatically sets the specified conversation's title.
  614.  *
  615.  * This function takes OPT_IM_ALIAS_TAB into account, as well as the
  616.  * user's alias.
  617.  *
  618.  * @param conv The conversation.
  619.  */
  620. void gaim_conversation_autoset_title(GaimConversation *conv);
  621.  
  622. /**
  623.  * Returns the specified conversation's index in the parent window.
  624.  *
  625.  * @param conv The conversation.
  626.  *
  627.  * @return The current index in the parent window.
  628.  */
  629. int gaim_conversation_get_index(const GaimConversation *conv);
  630.  
  631. /**
  632.  * Sets the conversation's unseen state.
  633.  *
  634.  * @param conv  The conversation.
  635.  * @param state The new unseen state.
  636.  */
  637. void gaim_conversation_set_unseen(GaimConversation *conv,
  638.                                   GaimUnseenState state);
  639.  
  640. /**
  641.  * Returns the conversation's unseen state.
  642.  *
  643.  * @param conv The conversation.
  644.  *
  645.  * @return The conversation's unseen state.
  646.  */
  647. GaimUnseenState gaim_conversation_get_unseen(const GaimConversation *conv);
  648.  
  649. /**
  650.  * Sets the specified conversation's name.
  651.  *
  652.  * @param conv The conversation.
  653.  * @param name The conversation's name.
  654.  */
  655. void gaim_conversation_set_name(GaimConversation *conv, const char *name);
  656.  
  657. /**
  658.  * Returns the specified conversation's name.
  659.  *
  660.  * @param conv The conversation.
  661.  *
  662.  * @return The conversation's name.
  663.  */
  664. const char *gaim_conversation_get_name(const GaimConversation *conv);
  665.  
  666. /**
  667.  * Enables or disables logging for this conversation.
  668.  *
  669.  * @param conv The conversation.
  670.  * @param log  @c TRUE if logging should be enabled, or @c FALSE otherwise.
  671.  */
  672. void gaim_conversation_set_logging(GaimConversation *conv, gboolean log);
  673.  
  674. /**
  675.  * Returns whether or not logging is enabled for this conversation.
  676.  *
  677.  * @param conv The conversation.
  678.  *
  679.  * @return @c TRUE if logging is enabled, or @c FALSE otherwise.
  680.  */
  681. gboolean gaim_conversation_is_logging(const GaimConversation *conv);
  682.  
  683. /**
  684.  * Returns the specified conversation's send history.
  685.  *
  686.  * @param conv The conversation.
  687.  *
  688.  * @return The conversation's send history.
  689.  */
  690. GList *gaim_conversation_get_send_history(const GaimConversation *conv);
  691.  
  692. /**
  693.  * Sets the specified conversation's history.
  694.  *
  695.  * @param conv    The conversation.
  696.  * @param history The history.
  697.  */
  698. void gaim_conversation_set_history(GaimConversation *conv, GString *history);
  699.  
  700. /**
  701.  * Returns the specified conversation's history.
  702.  *
  703.  * @param conv The conversation.
  704.  *
  705.  * @return The conversation's history.
  706.  */
  707. GString *gaim_conversation_get_history(const GaimConversation *conv);
  708.  
  709. /**
  710.  * Returns the specified conversation's parent window.
  711.  *
  712.  * @param conv The conversation.
  713.  *
  714.  * @return The conversation's parent window.
  715.  */
  716. GaimConvWindow *gaim_conversation_get_window(const GaimConversation *conv);
  717.  
  718. /**
  719.  * Returns the specified conversation's IM-specific data.
  720.  *
  721.  * If the conversation type is not GAIM_CONV_IM, this will return @c NULL.
  722.  *
  723.  * @param conv The conversation.
  724.  *
  725.  * @return The IM-specific data.
  726.  */
  727. GaimConvIm *gaim_conversation_get_im_data(const GaimConversation *conv);
  728.  
  729. #define GAIM_CONV_IM(c) (gaim_conversation_get_im_data(c))
  730.  
  731. /**
  732.  * Returns the specified conversation's chat-specific data.
  733.  *
  734.  * If the conversation type is not GAIM_CONV_CHAT, this will return @c NULL.
  735.  *
  736.  * @param conv The conversation.
  737.  *
  738.  * @return The chat-specific data.
  739.  */
  740. GaimConvChat *gaim_conversation_get_chat_data(const GaimConversation *conv);
  741.  
  742. #define GAIM_CONV_CHAT(c) (gaim_conversation_get_chat_data(c))
  743.  
  744. /**
  745.  * Sets extra data for a conversation.
  746.  *
  747.  * @param conv The conversation.
  748.  * @param key  The unique key.
  749.  * @param data The data to assign.
  750.  */
  751. void gaim_conversation_set_data(GaimConversation *conv, const char *key,
  752.                                 gpointer data);
  753.  
  754. /**
  755.  * Returns extra data in a conversation.
  756.  *
  757.  * @param conv The conversation.
  758.  * @param key  The unqiue key.
  759.  *
  760.  * @return The data associated with the key.
  761.  */
  762. gpointer gaim_conversation_get_data(GaimConversation *conv, const char *key);
  763.  
  764. /**
  765.  * Returns a list of all conversations.
  766.  *
  767.  * This list includes both IMs and chats.
  768.  *
  769.  * @return A GList of all conversations.
  770.  */
  771. GList *gaim_get_conversations(void);
  772.  
  773. /**
  774.  * Returns a list of all IMs.
  775.  *
  776.  * @return A GList of all IMs.
  777.  */
  778. GList *gaim_get_ims(void);
  779.  
  780. /**
  781.  * Returns a list of all chats.
  782.  *
  783.  * @return A GList of all chats.
  784.  */
  785. GList *gaim_get_chats(void);
  786.  
  787. /**
  788.  * Finds the conversation with the specified name.
  789.  *
  790.  * @param name The name of the conversation.
  791.  *
  792.  * @return The conversation if found, or @c NULL otherwise.
  793.  */
  794. GaimConversation *gaim_find_conversation(const char *name);
  795.  
  796. /**
  797.  * Finds a conversation with the specified name and user.
  798.  *
  799.  * @param name The name of the conversation.
  800.  * @param account The gaim_account associated with the conversation.
  801.  *
  802.  * @return The conversation if found, or @c NULL otherwise.
  803.  */
  804. GaimConversation *gaim_find_conversation_with_account(
  805.         const char *name, const GaimAccount *account);
  806.  
  807. /**
  808.  * Writes to a conversation window.
  809.  *
  810.  * This function should not be used to write IM or chat messages. Use
  811.  * gaim_conv_im_write() and gaim_conv_chat_write() instead. Those functions will
  812.  * most likely call this anyway, but they may do their own formatting,
  813.  * sound playback, etc.
  814.  *
  815.  * This can be used to write generic messages, such as "so and so closed
  816.  * the conversation window."
  817.  *
  818.  * @param conv    The conversation.
  819.  * @param who     The user who sent the message.
  820.  * @param message The message.
  821.  * @param flags   The message flags.
  822.  * @param mtime   The time the message was sent.
  823.  *
  824.  * @see gaim_conv_im_write()
  825.  * @see gaim_conv_chat_write()
  826.  */
  827. void gaim_conversation_write(GaimConversation *conv, const char *who,
  828.         const char *message, GaimMessageFlags flags,
  829.         time_t mtime);
  830.  
  831.  
  832. /**
  833.     Set the features as supported for the given conversation.
  834.     @param conv      The conversation
  835.     @param features  Bitset defining supported features
  836. */
  837. void gaim_conversation_set_features(GaimConversation *conv,
  838.         GaimConnectionFlags features);
  839.  
  840.  
  841. /**
  842.     Get the features supported by the given conversation.
  843.     @param conv  The conversation
  844. */
  845. GaimConnectionFlags gaim_conversation_get_features(GaimConversation *conv);            
  846.  
  847.  
  848. /**
  849.  * Updates the progress bar on a conversation window
  850.  * (if one exists in the UI).
  851.  *
  852.  * This is used for loading images typically.
  853.  *
  854.  * @param conv    The conversation.
  855.  * @param percent The percentage.
  856.  */
  857. void gaim_conversation_update_progress(GaimConversation *conv, float percent);
  858.  
  859. /**
  860.  * Determines if a conversation has focus
  861.  *
  862.  * @param conv    The conversation.
  863.  *
  864.  * @return @c TRUE if the conversation has focus, @c FALSE if
  865.  * it does not or the UI does not have a concept of conversation focus
  866.  */
  867. gboolean gaim_conversation_has_focus(GaimConversation *conv);
  868.  
  869. /**
  870.  * Updates the visual status and UI of a conversation.
  871.  *
  872.  * @param conv The conversation.
  873.  * @param type The update type.
  874.  */
  875. void gaim_conversation_update(GaimConversation *conv, GaimConvUpdateType type);
  876.  
  877. /**
  878.  * Calls a function on each conversation.
  879.  *
  880.  * @param func The function.
  881.  */
  882. void gaim_conversation_foreach(void (*func)(GaimConversation *conv));
  883.  
  884. /*@}*/
  885.  
  886.  
  887. /**************************************************************************/
  888. /** @name IM Conversation API                                             */
  889. /**************************************************************************/
  890. /*@{*/
  891.  
  892. /**
  893.  * Gets an IM's parent conversation.
  894.  *
  895.  * @param im The IM.
  896.  *
  897.  * @return The parent conversation.
  898.  */
  899. GaimConversation *gaim_conv_im_get_conversation(const GaimConvIm *im);
  900.  
  901. /**
  902.  * Sets the IM's buddy icon.
  903.  *
  904.  * This should only be called from within Gaim. You probably want to
  905.  * call gaim_buddy_icon_set_data().
  906.  *
  907.  * @param im   The IM.
  908.  * @param icon The buddy icon.
  909.  *
  910.  * @see gaim_buddy_icon_set_data()
  911.  */
  912. void gaim_conv_im_set_icon(GaimConvIm *im, GaimBuddyIcon *icon);
  913.  
  914. /**
  915.  * Returns the IM's buddy icon.
  916.  *
  917.  * @param im The IM.
  918.  *
  919.  * @return The buddy icon.
  920.  */
  921. GaimBuddyIcon *gaim_conv_im_get_icon(const GaimConvIm *im);
  922.  
  923. /**
  924.  * Sets the IM's typing state.
  925.  *
  926.  * @param im    The IM.
  927.  * @param state The typing state.
  928.  */
  929. void gaim_conv_im_set_typing_state(GaimConvIm *im, GaimTypingState state);
  930.  
  931. /**
  932.  * Returns the IM's typing state.
  933.  *
  934.  * @param im The IM.
  935.  *
  936.  * @return The IM's typing state.
  937.  */
  938. GaimTypingState gaim_conv_im_get_typing_state(const GaimConvIm *im);
  939.  
  940. /**
  941.  * Starts the IM's typing timeout.
  942.  *
  943.  * @param im      The IM.
  944.  * @param timeout The timeout.
  945.  */
  946. void gaim_conv_im_start_typing_timeout(GaimConvIm *im, int timeout);
  947.  
  948. /**
  949.  * Stops the IM's typing timeout.
  950.  *
  951.  * @param im The IM.
  952.  */
  953. void gaim_conv_im_stop_typing_timeout(GaimConvIm *im);
  954.  
  955. /**
  956.  * Returns the IM's typing timeout.
  957.  *
  958.  * @param im The IM.
  959.  *
  960.  * @return The timeout.
  961.  */
  962. guint gaim_conv_im_get_typing_timeout(const GaimConvIm *im);
  963.  
  964. /**
  965.  * Sets the IM's time until it should send another typing notification.
  966.  *
  967.  * @param im  The IM.
  968.  * @param val The time.
  969.  */
  970. void gaim_conv_im_set_type_again(GaimConvIm *im, time_t val);
  971.  
  972. /**
  973.  * Returns the IM's time until it should send another typing notification.
  974.  *
  975.  * @param im The IM.
  976.  *
  977.  * @return The time.
  978.  */
  979. time_t gaim_conv_im_get_type_again(const GaimConvIm *im);
  980.  
  981. /**
  982.  * Starts the IM's type again timeout.
  983.  *
  984.  * @param im      The IM.
  985.  */
  986. void gaim_conv_im_start_type_again_timeout(GaimConvIm *im);
  987.  
  988. /**
  989.  * Stops the IM's type again timeout.
  990.  *
  991.  * @param im The IM.
  992.  */
  993. void gaim_conv_im_stop_type_again_timeout(GaimConvIm *im);
  994.  
  995. /**
  996.  * Returns the IM's type again timeout interval.
  997.  *
  998.  * @param im The IM.
  999.  *
  1000.  * @return The type again timeout interval.
  1001.  */
  1002. guint gaim_conv_im_get_type_again_timeout(const GaimConvIm *im);
  1003.  
  1004. /**
  1005.  * Updates the visual typing notification for an IM conversation.
  1006.  *
  1007.  * @param im The IM.
  1008.  */
  1009. void gaim_conv_im_update_typing(GaimConvIm *im);
  1010.  
  1011. /**
  1012.  * Writes to an IM.
  1013.  *
  1014.  * @param im      The IM.
  1015.  * @param who     The user who sent the message.
  1016.  * @param message The message to write.
  1017.  * @param flags   The message flags.
  1018.  * @param mtime   The time the message was sent.
  1019.  */
  1020. void gaim_conv_im_write(GaimConvIm *im, const char *who,
  1021.                         const char *message, GaimMessageFlags flags,
  1022.                         time_t mtime);
  1023.  
  1024. /**
  1025.  * Presents an IM-error to the user
  1026.  * 
  1027.  * This is a helper function to find a conversation, write an error to it, and
  1028.  * raise the window.  If a conversation with this user doesn't already exist,
  1029.  * the function will return FALSE and the calling function can attempt to present
  1030.  * the error another way (gaim_notify_error, most likely)
  1031.  *
  1032.  * @param who     The user this error is about
  1033.  * @param account The account this error is on
  1034.  * @param what    The error
  1035.  * @return        TRUE if the error was presented, else FALSE
  1036.  */
  1037. gboolean gaim_conv_present_error(const char *who, GaimAccount *account, const char *what);
  1038.  
  1039. /**
  1040.  * Sends a message to this IM conversation.
  1041.  *
  1042.  * @param im      The IM.
  1043.  * @param message The message to send.
  1044.  */
  1045. void gaim_conv_im_send(GaimConvIm *im, const char *message);
  1046.  
  1047. /*@}*/
  1048.  
  1049.  
  1050. /**************************************************************************/
  1051. /** @name Chat Conversation API                                           */
  1052. /**************************************************************************/
  1053. /*@{*/
  1054.  
  1055. /**
  1056.  * Gets a chat's parent conversation.
  1057.  *
  1058.  * @param chat The chat.
  1059.  *
  1060.  * @return The parent conversation.
  1061.  */
  1062. GaimConversation *gaim_conv_chat_get_conversation(const GaimConvChat *chat);
  1063.  
  1064. /**
  1065.  * Sets the list of users in the chat room.
  1066.  *
  1067.  * @note Calling this function will not update the display of the users.
  1068.  *       Please use gaim_conv_chat_add_user(), gaim_conv_chat_add_users(),
  1069.  *       gaim_conv_chat_remove_user(), and gaim_conv_chat_remove_users() instead.
  1070.  *
  1071.  * @param chat  The chat.
  1072.  * @param users The list of users.
  1073.  *
  1074.  * @return The list passed.
  1075.  */
  1076. GList *gaim_conv_chat_set_users(GaimConvChat *chat, GList *users);
  1077.  
  1078. /**
  1079.  * Returns a list of users in the chat room.
  1080.  *
  1081.  * @param chat The chat.
  1082.  *
  1083.  * @return The list of users.
  1084.  */
  1085. GList *gaim_conv_chat_get_users(const GaimConvChat *chat);
  1086.  
  1087. /**
  1088.  * Ignores a user in a chat room.
  1089.  *
  1090.  * @param chat The chat.
  1091.  * @param name The name of the user.
  1092.  */
  1093. void gaim_conv_chat_ignore(GaimConvChat *chat, const char *name);
  1094.  
  1095. /**
  1096.  * Unignores a user in a chat room.
  1097.  *
  1098.  * @param chat The chat.
  1099.  * @param name The name of the user.
  1100.  */
  1101. void gaim_conv_chat_unignore(GaimConvChat *chat, const char *name);
  1102.  
  1103. /**
  1104.  * Sets the list of ignored users in the chat room.
  1105.  *
  1106.  * @param chat    The chat.
  1107.  * @param ignored The list of ignored users.
  1108.  *
  1109.  * @return The list passed.
  1110.  */
  1111. GList *gaim_conv_chat_set_ignored(GaimConvChat *chat, GList *ignored);
  1112.  
  1113. /**
  1114.  * Returns the list of ignored users in the chat room.
  1115.  *
  1116.  * @param chat The chat.
  1117.  *
  1118.  * @return The list of ignored users.
  1119.  */
  1120. GList *gaim_conv_chat_get_ignored(const GaimConvChat *chat);
  1121.  
  1122. /**
  1123.  * Returns the actual name of the specified ignored user, if it exists in
  1124.  * the ignore list.
  1125.  *
  1126.  * If the user found contains a prefix, such as '+' or '\@', this is also
  1127.  * returned. The username passed to the function does not have to have this
  1128.  * formatting.
  1129.  *
  1130.  * @param chat The chat.
  1131.  * @param user The user to check in the ignore list.
  1132.  *
  1133.  * @return The ignored user if found, complete with prefixes, or @c NULL
  1134.  *         if not found.
  1135.  */
  1136. const char *gaim_conv_chat_get_ignored_user(const GaimConvChat *chat,
  1137.                                             const char *user);
  1138.  
  1139. /**
  1140.  * Returns @c TRUE if the specified user is ignored.
  1141.  *
  1142.  * @param chat The chat.
  1143.  * @param user The user.
  1144.  *
  1145.  * @return @c TRUE if the user is in the ignore list; @c FALSE otherwise.
  1146.  */
  1147. gboolean gaim_conv_chat_is_user_ignored(const GaimConvChat *chat,
  1148.                                         const char *user);
  1149.  
  1150. /**
  1151.  * Sets the chat room's topic.
  1152.  *
  1153.  * @param chat  The chat.
  1154.  * @param who   The user that set the topic.
  1155.  * @param topic The topic.
  1156.  */
  1157. void gaim_conv_chat_set_topic(GaimConvChat *chat, const char *who,
  1158.                               const char *topic);
  1159.  
  1160. /**
  1161.  * Returns the chat room's topic.
  1162.  *
  1163.  * @param chat The chat.
  1164.  *
  1165.  * @return The chat's topic.
  1166.  */
  1167. const char *gaim_conv_chat_get_topic(const GaimConvChat *chat);
  1168.  
  1169. /**
  1170.  * Sets the chat room's ID.
  1171.  *
  1172.  * @param chat The chat.
  1173.  * @param id   The ID.
  1174.  */
  1175. void gaim_conv_chat_set_id(GaimConvChat *chat, int id);
  1176.  
  1177. /**
  1178.  * Returns the chat room's ID.
  1179.  *
  1180.  * @param chat The chat.
  1181.  *
  1182.  * @return The ID.
  1183.  */
  1184. int gaim_conv_chat_get_id(const GaimConvChat *chat);
  1185.  
  1186. /**
  1187.  * Writes to a chat.
  1188.  *
  1189.  * @param chat    The chat.
  1190.  * @param who     The user who sent the message.
  1191.  * @param message The message to write.
  1192.  * @param flags   The flags.
  1193.  * @param mtime   The time the message was sent.
  1194.  */
  1195. void gaim_conv_chat_write(GaimConvChat *chat, const char *who,
  1196.                           const char *message, GaimMessageFlags flags,
  1197.                           time_t mtime);
  1198.  
  1199. /**
  1200.  * Sends a message to this chat conversation.
  1201.  *
  1202.  * @param chat    The chat.
  1203.  * @param message The message to send.
  1204.  */
  1205. void gaim_conv_chat_send(GaimConvChat *chat, const char *message);
  1206.  
  1207. /**
  1208.  * Adds a user to a chat.
  1209.  *
  1210.  * @param chat        The chat.
  1211.  * @param user        The user to add.
  1212.  * @param extra_msg   An extra message to display with the join message.
  1213.  * @param flags       The users flags
  1214.  * @param new_arrival Decides whether or not to show a join notice.
  1215.  */
  1216. void gaim_conv_chat_add_user(GaimConvChat *chat, const char *user,
  1217.                              const char *extra_msg, GaimConvChatBuddyFlags flags,
  1218.                              gboolean new_arrival);
  1219.  
  1220. /**
  1221.  * Adds a list of users to a chat.
  1222.  *
  1223.  * The data is copied from @a users, so it is up to the developer to
  1224.  * free this list after calling this function.
  1225.  *
  1226.  * @param chat      The chat.
  1227.  * @param users     The list of users to add.
  1228.  * @param flags     The list of flags for each user.
  1229.  */
  1230. void gaim_conv_chat_add_users(GaimConvChat *chat, GList *users, GList *flags);
  1231.  
  1232. /**
  1233.  * Renames a user in a chat.
  1234.  *
  1235.  * @param chat     The chat.
  1236.  * @param old_user The old username.
  1237.  * @param new_user The new username.
  1238.  */
  1239. void gaim_conv_chat_rename_user(GaimConvChat *chat, const char *old_user,
  1240.                                 const char *new_user);
  1241.  
  1242. /**
  1243.  * Removes a user from a chat, optionally with a reason.
  1244.  *
  1245.  * It is up to the developer to free this list after calling this function.
  1246.  *
  1247.  * @param chat   The chat.
  1248.  * @param user   The user that is being removed.
  1249.  * @param reason The optional reason given for the removal. Can be @c NULL.
  1250.  */
  1251. void gaim_conv_chat_remove_user(GaimConvChat *chat, const char *user,
  1252.                                 const char *reason);
  1253.  
  1254. /**
  1255.  * Removes a list of users from a chat, optionally with a single reason.
  1256.  *
  1257.  * @param chat   The chat.
  1258.  * @param users  The users that are being removed.
  1259.  * @param reason The optional reason given for the removal. Can be @c NULL.
  1260.  */
  1261. void gaim_conv_chat_remove_users(GaimConvChat *chat, GList *users,
  1262.                                  const char *reason);
  1263.  
  1264. /**
  1265.  * Finds a user in a chat
  1266.  *
  1267.  * @param chat   The chat.
  1268.  * @param user   The user to look for.
  1269.  *
  1270.  * @return TRUE if the user is in the chat, FALSE if not
  1271.  */
  1272. gboolean gaim_conv_chat_find_user(GaimConvChat *chat, const char *user);
  1273.  
  1274. /**
  1275.  * Set a users flags in a chat
  1276.  *
  1277.  * @param chat   The chat.
  1278.  * @param user   The user to update.
  1279.  * @param flags  The new flags.
  1280.  */
  1281. void gaim_conv_chat_user_set_flags(GaimConvChat *chat, const char *user,
  1282.                                    GaimConvChatBuddyFlags flags);
  1283.  
  1284. /**
  1285.  * Get the flags for a user in a chat
  1286.  *
  1287.  * @param chat   The chat.
  1288.  * @param user   The user to find the flags for
  1289.  *
  1290.  * @return The flags for the user
  1291.  */
  1292. GaimConvChatBuddyFlags gaim_conv_chat_user_get_flags(GaimConvChat *chat,
  1293.                                                      const char *user);
  1294.  
  1295. /**
  1296.  * Clears all users from a chat.
  1297.  *
  1298.  * @param chat The chat.
  1299.  */
  1300. void gaim_conv_chat_clear_users(GaimConvChat *chat);
  1301.  
  1302. /**
  1303.  * Sets your nickname (used for hilighting) for a chat.
  1304.  *
  1305.  * @param chat The chat.
  1306.  * @param nick The nick.
  1307.  */
  1308. void gaim_conv_chat_set_nick(GaimConvChat *chat, const char *nick);
  1309.  
  1310. /**
  1311.  * Gets your nickname (used for hilighting) for a chat.
  1312.  *
  1313.  * @param chat The chat.
  1314.  * @return  The nick.
  1315.  */
  1316. const char *gaim_conv_chat_get_nick(GaimConvChat *chat);
  1317.  
  1318. /**
  1319.  * Finds a chat with the specified chat ID.
  1320.  *
  1321.  * @param gc The gaim_connection.
  1322.  * @param id The chat ID.
  1323.  *
  1324.  * @return The chat conversation.
  1325.  */
  1326. GaimConversation *gaim_find_chat(const GaimConnection *gc, int id);
  1327.  
  1328. /**
  1329.  * Lets the core know we left a chat, without destroying it.
  1330.  * Called from serv_got_chat_left().
  1331.  *
  1332.  * @param chat The chat.
  1333.  */
  1334. void gaim_conv_chat_left(GaimConvChat *chat);
  1335.  
  1336. /**
  1337.  * Returns true if we're no longer in this chat,
  1338.  * and just left the window open.
  1339.  *
  1340.  * @param chat The chat.
  1341.  *
  1342.  * @return @c TRUE if we left the chat already, @c FALSE if
  1343.  * we're still there.
  1344.  */
  1345. gboolean gaim_conv_chat_has_left(GaimConvChat *chat);
  1346.  
  1347. /**
  1348.  * Creates a new chat buddy
  1349.  *
  1350.  * @param name The name.
  1351.  * @param flags The flags.
  1352.  *
  1353.  * @return The new chat buddy
  1354.  */
  1355. GaimConvChatBuddy *gaim_conv_chat_cb_new(const char *name,
  1356.                                         GaimConvChatBuddyFlags flags);
  1357.  
  1358. /**
  1359.  * Find a chat buddy in a chat
  1360.  *
  1361.  * @param chat The chat.
  1362.  * @param name The name of the chat buddy to find.
  1363.  */
  1364. GaimConvChatBuddy *gaim_conv_chat_cb_find(GaimConvChat *chat, const char *name);
  1365.  
  1366. /**
  1367.  * Get the name of a chat buddy
  1368.  *
  1369.  * @param cb    The chat buddy.
  1370.  *
  1371.  * @return The name of the chat buddy.
  1372.  */
  1373. const char *gaim_conv_chat_cb_get_name(GaimConvChatBuddy *cb);
  1374.  
  1375. /**
  1376.  * Destroys a chat buddy
  1377.  *
  1378.  * @param cb The chat buddy to destroy
  1379.  */
  1380. void gaim_conv_chat_cb_destroy(GaimConvChatBuddy *cb);
  1381.  
  1382. /*@}*/
  1383.  
  1384. /**************************************************************************/
  1385. /** @name Conversation Placement API                                      */
  1386. /**************************************************************************/
  1387. /*@{*/
  1388.  
  1389. /**
  1390.  * Returns a GList containing the IDs and Names of the registered placement
  1391.  * functions.
  1392.  *
  1393.  * @return The list of IDs and names.
  1394.  */
  1395. GList *gaim_conv_placement_get_options(void);
  1396.  
  1397. /**
  1398.  * Adds a conversation placement function to the list of possible functions.
  1399.  *
  1400.  * @param id   The unique ID of the placement function.
  1401.  * @param name The name of the function.
  1402.  * @param fnc  A pointer to the function.
  1403.  */
  1404. void gaim_conv_placement_add_fnc(const char *id, const char *name,
  1405.                                  GaimConvPlacementFunc fnc);
  1406.  
  1407. /**
  1408.  * Removes a conversation placement function from the list of possible
  1409.  * functions.
  1410.  *
  1411.  * @param id The id of the function.
  1412.  */
  1413. void gaim_conv_placement_remove_fnc(const char *id);
  1414.  
  1415. /**
  1416.  * Returns the name of the conversation placement function at the
  1417.  * specified id.
  1418.  *
  1419.  * @param id The id.
  1420.  *
  1421.  * @return The name of the function, or @c NULL if this id is invalid.
  1422.  */
  1423. const char *gaim_conv_placement_get_name(const char *id);
  1424.  
  1425. /**
  1426.  * Returns a pointer to the conversation placement function at the
  1427.  * specified id.
  1428.  *
  1429.  * @param id The id.
  1430.  *
  1431.  * @return A pointer to the function.
  1432.  */
  1433. GaimConvPlacementFunc gaim_conv_placement_get_fnc(const char *id);
  1434.  
  1435. /**
  1436.  * Sets the current conversation placement function.
  1437.  *
  1438.  * @param func The new conversation placement function.
  1439.  */
  1440. void gaim_conv_placement_set_current_func(GaimConvPlacementFunc func);
  1441.  
  1442. /**
  1443.  * Returns the current conversation placement function.
  1444.  *
  1445.  * @return The current conversation placement function.
  1446.  */
  1447. GaimConvPlacementFunc gaim_conv_placement_get_current_func(void);
  1448.  
  1449. /**
  1450.  * Returns the id of the specified conversation placement function.
  1451.  *
  1452.  * @param fnc A pointer to the registered function.
  1453.  *
  1454.  * @return The id of the conversation, or NULL if the function is not
  1455.  *         registered.
  1456.  */
  1457. const char *gaim_conv_placement_get_fnc_id(GaimConvPlacementFunc fnc);
  1458.  
  1459. /*@}*/
  1460.  
  1461. /**************************************************************************/
  1462. /** @name UI Registration Functions                                       */
  1463. /**************************************************************************/
  1464. /*@{*/
  1465.  
  1466. /**
  1467.  * Sets the UI operations structure to be used in all gaim conversation
  1468.  * windows.
  1469.  *
  1470.  * @param ops The UI operations structure.
  1471.  */
  1472. void gaim_conversations_set_win_ui_ops(GaimConvWindowUiOps *ops);
  1473.  
  1474. /**
  1475.  * Returns the gaim window UI operations structure to be used in
  1476.  * new windows.
  1477.  *
  1478.  * @return A filled-out GaimConvWindowUiOps structure.
  1479.  */
  1480. GaimConvWindowUiOps *gaim_conversations_get_win_ui_ops(void);
  1481.  
  1482.  
  1483. /*@}*/
  1484.  
  1485. /**************************************************************************/
  1486. /** @name Conversations Subsystem                                         */
  1487. /**************************************************************************/
  1488. /*@{*/
  1489.  
  1490. /**
  1491.  * Returns the conversation subsystem handle.
  1492.  *
  1493.  * @return The conversation subsystem handle.
  1494.  */
  1495. void *gaim_conversations_get_handle(void);
  1496.  
  1497. /**
  1498.  * Initializes the conversation subsystem.
  1499.  */
  1500. void gaim_conversations_init(void);
  1501.  
  1502. /**
  1503.  * Uninitializes the conversation subsystem.
  1504.  */
  1505. void gaim_conversations_uninit(void);
  1506.  
  1507. /*@}*/
  1508.  
  1509. #ifdef __cplusplus
  1510. }
  1511. #endif
  1512.  
  1513. #endif /* _GAIM_CONVERSATION_H_ */
  1514.